<?php
/*
* Copyright (c) 2010 by Cediti
*
* You may distribute under the terms of either the GNU Lesser General
* Public License or the new BSD License, as specified in the README file.
*/

/**
 * The Navigation Services (getDescendants, getChildren, getFolderParent,
 * getObjectParents, getCheckedoutDocs), are used to traverse the folder hierarchy
 * in a CMIS Repository, and to locate Documents that are checked out.
 * 
 */
interface Cmis_Services_Navigation extends Cmis_Services_Interface
{
	/**
	 * Gets the list of child objects contained in the specified folder
	 * 
	 * If the Repository supports the optional “VersionSpecificFiling” capability,
	 * then the repository MUST return the document versions filed in the specified
	 * folder. Otherwise, the latest version of the documents MUST be returned.
	 *
	 * @param Cmis_Repository_Id $repositoryId The identifier for the Repository
	 * @param string $folderId The identifier for the folder
     * @param int $maxItems
     * @param int $skipCount
     * @param string $orderBy
     * @param string $filter
     * @param Enum $includeRelationships
     * @param string $renditionFilter
	 * @param bool $includeAllowableActions
	 * @param bool $includePathSegment
	 * @return array[Cmis_Repository_Entry] 0: the folder object 
	 */
	public function getChildren(Cmis_Repository_Id $repositoryId, Cmis_Repository_Id $folderId, $maxItems = null, $skipCount = null, $orderBy = null, $filter = null, $includeRelationships = null, $renditionFilter = null, $includeAllowableActions = false, $includePathSegment = false);

    /**
     * Gets the set of descendant objects contained in the specified folder or any of its child-folders.
     * 
     * This method does NOT support paging as defined in the ‎2.2.1.1 Paging section.
     * The order in which results are returned is respository-specific..
     * If the Repository supports the optional capability capabilityVersionSpecificFiling,
     * then the repository MUST return the document versions filed in the specified
     * folder or its descendant folders.  Otherwise, the latest version of the
     * documents MUST be returned.
     * If the Repository supports the optional capability capabilityMutlifiling
     * and the same document is encountered multiple times in the hierarchy, then
     * the repository MUST return that document each time is encountered.
     *
     * @param Cmis_Repository_Id $repositoryId The identifier for the Repository
     * @param string $folderId The identifier for the folder
     * @param int $depth
     * @param string $filter
     * @param Enum includeRelationships
     * @param string renditionFilter
     * @param bool $includeAllowableActions
     * @param bool $includePathSegment
     * @see http://docs.oasis-open.org/cmis/CMIS/v1.0/cd06/cmis-spec-v1.0.html#_getDescendants
     * @return Cmis_Response
     */
    public function getDescendants(Cmis_Repository_Id $repositoryId, Cmis_Repository_Id $folderId, $depth = null, $filter = null, $includeRelationships = null, $renditionFilter = null, $includeAllowableActions = false, $includePathSegment = false);
    
    /**
     * Gets the set of descendant folder objects contained in the specified folder.
     * 
     * This method does NOT support paging as defined in the 2.2.1.1 Paging section.
     * The order in which results are returned is respository-specific
     * 
     * @param Cmis_Repository_Id $repositoryId The identifier for the Repository
     * @param string $folderId The identifier for the folder
     * @param int $depth The number of levels of depth in the folder hierarchy
     *  from which to return results. Valid values are:
     *    _ 1: Return only folders that are children of the folder.
     *    _ <Integer value greater than 1>: Return only folders that are children
     *    of the folder and descendant folders up to <value> levels deep.
     *    _ -1: Return ALL descendant folders at all depth levels in the CMIS hierarchy
     *    _ The default value is repository specific and SHOULD be at least 2 or -1
     * @param string $filter
     * @param Enum includeRelationships
     * @param string renditionFilter
     * @param bool $includeAllowableActions
     * @param bool $includePathSegment Defaults to FALSE. If TRUE, returns a PathSegment
     *  for each child object for use in constructing that object's path.
     * @see http://docs.oasis-open.org/cmis/CMIS/v1.0/cd07/cmis-spec-v1.0.html#_getFolderTree
     * @return array[id:title]
     */
    public function getFolderTree(Cmis_Repository_Id $repositoryId, Cmis_Repository_Id $folderId, $depth = null, $filter = null, $includeRelationships = null, $renditionFilter = null, $includeAllowableActions = false, $includePathSegment = false);

	/**
	 * Gets the parent folder object for the specified folder object.  
	 *
	 * @param Cmis_Repository_Id $repositoryId The identifier for the Repository
	 * @param string $folderId
     * @param string $filter
     * @see http://docs.oasis-open.org/cmis/CMIS/v1.0/cd06/cmis-spec-v1.0.html#_getFolderParent
	 * @return Cmis_Response
	 */
	public function getFolderParent(Cmis_Repository_Id $repositoryId, Cmis_Repository_Id $folderId, $filter = null);

	/**
	 * Gets the parent folder(s) for the specified non-folder, fileable object.
	 *
	 * @param Cmis_Repository_Id $repositoryId The identifier for the Repository
	 * @param string $objectId The identifier for the object.
	 * @param string $filter
	 * @param Enum $includeRelationships
	 * @param string $renditionFilter
	 * @param bool $includeAllowableActions
	 * @param bool $includeRelativePathSegment
     * @see http://docs.oasis-open.org/cmis/CMIS/v1.0/cd06/cmis-spec-v1.0.html#_getObjectParents
	 * @return Cmis_Response
	 */
	public function getObjectParents(Cmis_Repository_Id $repositoryId, Cmis_Repository_Id $objectId, $filter = null, $includeRelationships = null, $renditionFilter = null, $includeAllowableActions = false, $includeRelativePathSegment = false);

	/**
	 * Gets the list of documents that are checked out that the user has access to.
	 *
	 * @param Cmis_Repository_Id repositoryId The identifier for the Repository
	 * @param string folderId The identifier for a folder in the repository from which documents should be returned.
	 * @param int $maxItems
	 * @param int $skipCount
	 * @param string $orderBy
	 * @param string $filter
	 * @param Enum $includeRelationships
	 * @param string $renditionFilter
	 * @param bool $includeAllowableActions
     * @see http://docs.oasis-open.org/cmis/CMIS/v1.0/cd06/cmis-spec-v1.0.html#_getCheckedoutDocuments
	 * @return Cmis_Response
	 */
	public function getCheckedoutDocuments(Cmis_Repository_Id $repositoryId, Cmis_Repository_Id $folderId = null, $maxItems = null, $skipCount = null, $orderBy = null, $filter = null, $includeRelationships = null, $renditionFilter = null, $includeAllowableActions = false);
}

# EOF
